home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Visual Cafe 3
/
Visual Cafe 3.ISO
/
Vcafe
/
JFC.bin
/
BoundedRangeModel.java
< prev
next >
Wrap
Text File
|
1998-06-30
|
8KB
|
248 lines
/*
* @(#)BoundedRangeModel.java 1.16 98/02/26
*
* Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
*
* This software is the confidential and proprietary information of Sun
* Microsystems, Inc. ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Sun.
*
* SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
* SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
* IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
* PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
* SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
* THIS SOFTWARE OR ITS DERIVATIVES.
*
*/
package com.sun.java.swing;
import com.sun.java.swing.event.*;
/**
* Defines the data model used by components like Sliders and ProgressBars.
* Defines four interrelated integer properties: minimum, maximum, extent
* and value. These four integers define two nested ranges like this:
* <pre>
* minimum <= value <= value+extent <= maximum
* </pre>
* The outer range is <code>minimum,maximum</code> and the inner
* range is <code>value,value+extent</code>. The inner range
* must lie within the outer one, i.e. <code>value</code> must be
* less than or equal to <code>maximum</code> and <code>value+extent</code>
* must greater than or equal to <code>minimum</code>, and <code>maximum</code>
* must be greater than or equal to <code>minimum</code>.
* There are a few features of this model that one might find a little
* surprising. These quirks exist for the convenience of the
* Swing BoundedRangeModel clients like like Slider and ScrollBar.
* <ul>
* <li>
* The minimum and maximum set methods "correct" the other
* three properties to acommodate their new value argument. For
* example setting the model's minimum may change its maximum, value,
* and extent properties (in that order), to maintain the constraints
* specified above.
*
* <li>
* The value and extent set methods "correct" their argument to
* fit within the limits defined by the other three properties.
* For example if <code>value == maximum</code>, <code>setExtent(10)</code>
* would change the extent (back) to zero.
*
* <li>
* The four BoundedRangeModel values are defined as Java Beans properties
* however Swing ChangeEvents are used to notify clients of changes rather
* than PropertyChangeEvents. This was done to keep the overhead of monitoring
* a BoundedRangeModel low. Changes are often reported at MouseDragged rates.
* </ul>
*
* @version 1.16 02/26/98
* @author Hans Muller
* @see DefaultBoundedRangeModel
*/
public interface BoundedRangeModel
{
/**
* Returns the minimum acceptable value.
*
* @return the value of the minimum property
* @see #setMinimum
*/
int getMinimum();
/**
* Sets the model's minimum to <I>newMinimum</I>. The
* other three properties may be changed as well, to ensure
* that:
* <pre>
* minimum <= value <= value+extent <= maximum
* </pre>
* <p>
* Notifies any listeners if the model changes.
*
* @param newMinimum the model's new minimum
* @see #getMinimum
* @see #addChangeListener
*/
void setMinimum(int newMinimum);
/**
* Returns the model's maximum. Note that the upper
* limit on the model's value is (maximum - extent).
*
* @return the value of the maximum property.
* @see #setMaximum
* @see #setExtent
*/
int getMaximum();
/**
* Sets the model's maximum to <I>newMaximum</I>. The other
* three properties may be changed as well, to ensure that
* <pre>
* minimum <= value <= value+extent <= maximum
* </pre>
* <p>
* Notifies any listeners if the model changes.
*
* @param newMaximum the model's new maximum
* @see #getMaximum
* @see #addChangeListener
*/
void setMaximum(int newMaximum);
/**
* Returns the model's current value. Note that the upper
* limit on the model's value is <code>maximum - extent</code>
* and the lower limit is <code>minimum</code>.
*
* @return the model's value
* @see #setValue
*/
int getValue();
/**
* Sets the model's current value to <code>newValue</code> if <code>newValue</code>
* satisfies the model's constraints. Those constraints are:
* <pre>
* minimum <= value <= value+extent <= maximum
* </pre>
* Otherwise, if <code>newValue</code> is less than <code>minimum</code>
* it's set to <code>minimum</code>, if its greater than
* <code>maximum</code> then it's set to <code>maximum</code>, and
* if it's greater than <code>value+extent</code> then it's set to
* <code>value+extent</code>.
* <p>
* When a BoundedRange model is used with a scrollbar the value
* specifies the origin of the scrollbar knob (aka the "thumb" or
* "elevator"). The value usually represents the origin of the
* visible part of the object being scrolled.
* <p>
* Notifies any listeners if the model changes.
*
* @param newValue the model's new value
* @see #getValue
*/
void setValue(int newValue);
/**
* This attribute indicates that any upcoming changes to the value
* of the model should be considered a single event. This attribute
* will be set to true at the start of a series of changes to the value,
* and will be set to false when the value has finished changing. Normally
* this allows a listener to only take action when the final value change in
* committed, instead of having to do updates for all intermediate values.
* <p>
* Sliders and scrollbars use this property when a drag is underway.
*
* @param b true if the upcoming changes to the value property are part of a series
* @see #getValueIsAdjusting
*/
void setValueIsAdjusting(boolean b);
/**
* Returns true if the current changes to the value property are part
* of a series.
*
* @return the valueIsAdjustingProperty.
* @see #setValueIsAdjusting
*/
boolean getValueIsAdjusting();
/**
* Returns the model's extent, the length of the inner range that
* begins at the model's value.
*
* @return the value of the model's extent property
* @see #setExtent
* @see #setValue
*/
int getExtent();
/**
* Sets the model's extent. The <I>newExtent</I> is forced to
* be greater than or equal to zero and less than or equal to
* maximum - value.
* <p>
* When a BoundedRange model is used with a scrollbar the extent
* defines the length of the scrollbar knob (aka the "thumb" or
* "elevator"). The extent usually represents how much of the
* object being scrolled is visible.
* <p>
* Notifies any listeners if the model changes.
*
* @param newExtent the model's new extent
* @see #getExtent
* @see #setValue
*/
void setExtent(int newExtent);
/**
* This method sets all of the model's data with a single method call.
* The method results in a single change event being generated. This is
* convenient when you need to adjust all the model data simulaneously and
* do not want individual change events to occur.
*
* @see #setValue
* @see #setExtent
* @see #setMinimum
* @see #setMaximum
* @see #setValueIsAdjusting
*/
void setRangeProperties(int value, int extent, int min, int max, boolean adjusting);
/**
* Adds a ChangeListener to the model's listener list.
*
* @param x the ChangeListener to add
* @see #removeChangeListener
*/
void addChangeListener(ChangeListener x);
/**
* Removes a ChangeListener from the model's listener list.
*
* @param x the ChangeListener to remove
* @see #addChangeListener
*/
void removeChangeListener(ChangeListener x);
}